<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Formata&ccedil;&atilde;o dos Arquivos de Documenta&ccedil;&atilde;o - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/doc-standard.file-formatting.html">Inglês (English)</a></li>
    <li><a href="../pt-br/doc-standard.file-formatting.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="doc-standard.overview.html">Vis&atilde;o Geral</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="doc-standard.html">Norma sobre a documenta&ccedil;&atilde;o do Zend Framework</a></span><br />
                        <span class="home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="doc-standard.recommendations.html">Recomenda&ccedil;&otilde;es</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="doc-standard.file-formatting" class="section"><div class="info"><h1 class="title">Formatação dos Arquivos de Documentação</h1></div>
        

        <div class="section" id="doc-standard.file-formatting.xml-tags"><div class="info"><h1 class="title">Tags XML</h1></div>
            

            <p class="para">
                Cada arquivo do manual deve incluir as seguintes declarações <acronym class="acronym">XML</acronym>
                no topo do arquivo:
            </p>

            <pre class="programlisting brush: xml">
&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;!-- Reviewed: no --&gt;
</pre>


            <p class="para">
                Os arquivos <acronym class="acronym">XML</acronym> provenientes de traduções devem também incluir
                uma tag de revisão contendo a revisão do arquivo correspondente em inglês na qual a
                tradução se baseou.
            </p>

            <pre class="programlisting brush: xml">
&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;!-- EN-Revision: 14978 --&gt;
&lt;!-- Reviewed: no --&gt;
</pre>

        </div>

        <div class="section" id="doc-standard.file-formatting.max-line-length"><div class="info"><h1 class="title">Comprimento Máximo da Linha</h1></div>
            

            <p class="para">
                O comprimento máximo da linha, incluindo tags, atributos e indentação, não deve
                exceder 100 caracteres. Existe apenas uma exceção a essa regra: os pares de atributo
                e valor são autorizados a ultrapassar os 100 caracteres, desde que não seja
                permitido estarem separados.
            </p>
        </div>

        <div class="section" id="doc-standard.file-formatting.indentation"><div class="info"><h1 class="title">Indentação</h1></div>
            

            <p class="para">
                A indentação deve ser composta por 4 espaços. Tabs não são permitidos.
            </p>

            <p class="para">
                Tags que estão no mesmo nível devem ter a mesma indentação.
            </p>

            <pre class="programlisting brush: xml">
&lt;sect1&gt;
&lt;/sect1&gt;

&lt;sect1&gt;
&lt;/sect1&gt;
</pre>


            <p class="para">
                Tags que estão um nível abaixo da tag anterior devem ser indentadas com 4 espaços
                adicionais.
            </p>

            <pre class="programlisting brush: xml">
&lt;sect1&gt;
    &lt;sect2&gt;
    &lt;/sect2&gt;
&lt;/sect1&gt;
</pre>


            <p class="para">
                Vários elementos de bloco dentro de uma mesma linha não são permitidos, no entanto
                vários elementos inline são permitidos.
            </p>

            <pre class="programlisting brush: xml">
&lt;!-- NÃO PERMITIDO --&gt;
&lt;sect1&gt;&lt;sect2&gt;
&lt;/sect2&gt;&lt;/sect1&gt;

&lt;!-- PERMITIDO --&gt;
&lt;para&gt;
    &lt;classname&gt;Zend_Magic&lt;/classname&gt; não existe. &lt;classname&gt;Zend_Acl&lt;/classname&gt; existe.
&lt;/para&gt;
</pre>

        </div>

        <div class="section" id="doc-standard.file-formatting.line-termination"><div class="info"><h1 class="title">Terminação de Linha</h1></div>
            

            <p class="para">
                A terminação de linha segue a convenção para arquivos de texto do Unix. As linhas
                devem terminar com um simples caractere line feed (LF). Caracteres line feed são
                representados pelo ordinal 10 ou hexadecimal 0x0A.
            </p>

            <p class="para">
                Nota: Não utilize o carriage return (<acronym class="acronym">CR</acronym>), como na convenção dos
                sistemas operacionais da Apple (0x0D) ou a combinação carriage return - line feed
                (<acronym class="acronym">CRLF</acronym>) como no padrão para os sistemas operacionais Windows
                (0x0D, 0x0A).
            </p>
        </div>

        <div class="section" id="doc-standard.file-formatting.empty-tags"><div class="info"><h1 class="title">Tags vazias</h1></div>
            

            <p class="para">
                Tags vazias não são permitidas; todas as tags devem conter texto ou tags filhas.
            </p>

            <pre class="programlisting brush: xml">
&lt;!-- NÃO PERMITIDO --&gt;
&lt;para&gt;
    Algum texto. &lt;link&gt;&lt;/link&gt;
&lt;/para&gt;

&lt;para&gt;
&lt;/para&gt;
</pre>

        </div>

        <div class="section" id="doc-standard.file-formatting.whitespace"><div class="info"><h1 class="title">Uso de espaços em branco dentro de documentos</h1></div>
            

            <div class="section" id="doc-standard.file-formatting.whitespace.trailing"><div class="info"><h1 class="title">Espaço em branco dentro de tags</h1></div>
                

                <p class="para">
                    Não deve haver nada imediatamente apoś as tags de abertura de elementos de bloco
                    além de uma quebra linha (e a indentação na linha seguinte).
                </p>

                <pre class="programlisting brush: xml">
&lt;!-- NÃO PERMITIDO --&gt;
&lt;sect1&gt;ESPAÇO
&lt;/sect1&gt;
</pre>


                <p class="para">
                    Não deve haver espaço em branco imediatamente após as tags de abertura de
                    elementos inline.
                </p>

                <pre class="programlisting brush: xml">
&lt;!-- NÃO PERMITIDO --&gt;
Esta é a classe &lt;classname&gt; Zend_Class&lt;/classname&gt;.

&lt;!-- PERMITIDO --&gt;
Esta é a classe &lt;classname&gt;Zend_Class&lt;/classname&gt;.
</pre>


                <p class="para">
                    As tags de fechamento de elementos de bloco podem ser precedidos por espaços em
                    branco equivalentemente ao nível atual de indentação, mas não mais do que isso.
                </p>

                <pre class="programlisting brush: xml">
&lt;!-- NÃO PERMITIDO --&gt;
    &lt;sect1&gt;
     &lt;/sect1&gt;

&lt;!-- PERMITIDO --&gt;
    &lt;sect1&gt;
    &lt;/sect1&gt;
</pre>


                <p class="para">
                    As tags de fechamento de elementos inline não devem ser precedidas por nenhum
                    espaço em branco.
                </p>

                <pre class="programlisting brush: xml">
&lt;!-- NÃO PERMITIDO --&gt;
Esta é a classe &lt;classname&gt;Zend_Class &lt;/classname&gt;

&lt;!-- PERMITIDO --&gt;
Esta é a classe &lt;classname&gt;Zend_Class&lt;/classname&gt;
</pre>

            </div>

            <div class="section" id="doc-standard.file-formatting.whitespace.multiple-line-breaks"><div class="info"><h1 class="title">Várias quebras de linha</h1></div>
                

                <p class="para">
                    Várias quebras de linha dentro ou entre as tags não são permitidas.
                </p>

                <pre class="programlisting brush: xml">
&lt;!-- NÃO PERMITIDO --&gt;
&lt;para&gt;
    Algum texto...

    ... e mais texto
&lt;/para&gt;


&lt;para&gt;
    Outro parágrafo.
&lt;/para&gt;

&lt;!-- PERMITIDO --&gt;
&lt;para&gt;
    Algum texto...
    ... e mais texto
&lt;/para&gt;

&lt;para&gt;
    Outro parágrafo.
&lt;/para&gt;
</pre>

            </div>

            <div class="section" id="doc-standard.file-formatting.whitespace.tag-separation"><div class="info"><h1 class="title">Separação entre as tags</h1></div>
                

                <p class="para">
                    Tags em um mesmo nível devem ser separadas por uma linha em branco para melhorar
                    a legibilidade.
                </p>

                <pre class="programlisting brush: xml">
&lt;!-- NÃO PERMITIDO --&gt;
&lt;para&gt;
    Algum texto...
&lt;/para&gt;
&lt;para&gt;
    Mais texto...
&lt;/para&gt;

&lt;!-- PERMITIDO --&gt;
&lt;para&gt;
    Algum texto...
&lt;/para&gt;

&lt;para&gt;
    Mais texto...
&lt;/para&gt;
</pre>


                <p class="para">
                    O primeiro elemento filho de ser aberto diretamente abaixo de seu pai, sem linha
                    vazia entre eles. O último elemento filho deve ser fechado diretamente antes da
                    tag de fechamento de seu pai.
                </p>

                <pre class="programlisting brush: xml">
&lt;!-- NÃO PERMITIDO --&gt;
&lt;sect1&gt;

    &lt;sect2&gt;
    &lt;/sect2&gt;

    &lt;sect2&gt;
    &lt;/sect2&gt;

    &lt;sect2&gt;
    &lt;/sect2&gt;

&lt;/sect1&gt;

&lt;!-- PERMITIDO --&gt;
&lt;sect1&gt;
    &lt;sect2&gt;
    &lt;/sect2&gt;

    &lt;sect2&gt;
    &lt;/sect2&gt;

    &lt;sect2&gt;
    &lt;/sect2&gt;
&lt;/sect1&gt;
</pre>

            </div>
        </div>

        <div class="section" id="doc-standard.file-formatting.program-listing"><div class="info"><h1 class="title">Códigos de Exemplo</h1></div>
            

            <p class="para">
                A tag de abertura de <em class="emphasis">&lt;programlisting&gt;</em> deve indicar o
                atributo &quot;language&quot; adequado e ser indentado no mesmo nível que seus blocos irmãos.
            </p>

            <pre class="programlisting brush: xml">
&lt;para&gt;Parágrafo irmão.&lt;/para&gt;

&lt;programlisting language=&quot;php&quot;&gt;&lt;![CDATA[
</pre>


            <p class="para">
                <acronym class="acronym">CDATA</acronym> deve ser usado junto de todos os códigos de exemplo.
            </p>

            <p class="para">
                As seções de <em class="emphasis">&lt;programlisting&gt;</em> não devem conter quebras de
                linha ou espaços em branco no início ou no final da seção, uma vez que estas são
                representadas no resultado final.
            </p>

            <pre class="programlisting brush: xml">
&lt;!-- NÃO PERMITIDO --&gt;
&lt;programlisting language=&quot;php&quot;&gt;&lt;![CDATA[

$render = &quot;xxx&quot;;

]]&gt;&lt;/programlisting&gt;

&lt;!-- PERMITIDO --&gt;
&lt;programlisting language=&quot;php&quot;&gt;&lt;![CDATA[
$render = &quot;xxx&quot;;
]]&gt;&lt;/programlisting&gt;
</pre>


            <p class="para">
                As tags de fechamento de <acronym class="acronym">CDATA</acronym> e
                <em class="emphasis">&lt;programlisting&gt;</em> devem estar na mesma linha, sem qualquer
                indentação.
            </p>

            <pre class="programlisting brush: xml">
&lt;!-- NÃO PERMITIDO --&gt;
    &lt;programlisting language=&quot;php&quot;&gt;&lt;![CDATA[
$render = &quot;xxx&quot;;
]]&gt;
    &lt;/programlisting&gt;

&lt;!-- NÃO PERMITIDO --&gt;
    &lt;programlisting language=&quot;php&quot;&gt;&lt;![CDATA[
$render = &quot;xxx&quot;;
    ]]&gt;&lt;/programlisting&gt;

&lt;!-- PERMITIDO --&gt;
    &lt;programlisting language=&quot;php&quot;&gt;&lt;![CDATA[
$render = &quot;xxx&quot;;
]]&gt;&lt;/programlisting&gt;
</pre>


            <p class="para">
                A tag <em class="emphasis">&lt;programlisting&gt;</em> deve conter o atributo &quot;language&quot;
                com um valor correspondente ao conteúdo do código de exemplo. Os valores típicos
                incluem &quot;css&quot;, &quot;html&quot;, &quot;ini&quot;, &quot;javascript&quot;, &quot;php&quot;, &quot;text&quot;, e &quot;xml&quot;.
            </p>

            <pre class="programlisting brush: xml">
&lt;!-- PHP --&gt;
&lt;programlisting language=&quot;php&quot;&gt;&lt;![CDATA[

&lt;!-- Javascript --&gt;
&lt;programlisting language=&quot;javascript&quot;&gt;&lt;![CDATA[

&lt;!-- XML --&gt;
&lt;programlisting language=&quot;xml&quot;&gt;&lt;![CDATA[
</pre>


            <p class="para">
                Para códigos de exemplo que contenham apenas código <acronym class="acronym">PHP</acronym>, as tags
                do <acronym class="acronym">PHP</acronym> (por exemplo, &quot;&lt;?php&quot;, &quot;?&gt;&quot;) não são necessárias, e
                não devem ser usadas. Elas dificultam a legibilidade do código, e estão implícitas
                no uso do elemento <em class="emphasis">&lt;programlisting&gt;</em>.
            </p>

            <pre class="programlisting brush: xml">
&lt;!-- NÃO PERMITIDO --&gt;
&lt;programlisting language=&quot;php&quot;&lt;![CDATA[&lt;?php
    // ...
?&gt;]]&gt;&lt;/programlisting&gt;

&lt;programlisting language=&quot;php&quot;&lt;![CDATA[
&lt;?php
    // ...
?&gt;
]]&gt;&lt;/programlisting&gt;
</pre>


            <p class="para">
                Os comprimentos de linha dentro de códigos de exemplo devem seguir as <a href="coding-standard.php-file-formatting.html#coding-standard.php-file-formatting.max-line-length" class="link">recomendações das
                    normas de codificação</a>.
            </p>

            <p class="para">
                Evite utilizar  <span class="methodname">require_once()</span>,
                 <span class="methodname">require()</span>,  <span class="methodname">include_once()</span>, e
                 <span class="methodname">include()</span> dentro de exemplos em <acronym class="acronym">PHP</acronym>.
                Eles dificultam a legibilidade do código, e são basicamente evitados quando
                utiliza-se um carregador automático. Use-os apenas quando forem essenciais ao
                exemplo.
            </p>

            <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>Nunca utilize tags curtas</b><br /></span>
                

                <p class="para">
                    Tags curtas (por exemplo, &quot;&lt;?&quot;, &quot;&lt;?=&quot;) nunca devem ser usadas dentro do
                    elemento <em class="emphasis">programlisting</em> ou no restante da documentação.
                </p>
            </p></blockquote>
        </div>

        <div class="section" id="doc-standard.file-formatting.inline-tags"><div class="info"><h1 class="title">Notas sobre elementos inline específicos</h1></div>
            

            <div class="section" id="doc-standard.file-formatting.inline-tags.classname"><div class="info"><h1 class="title">classname</h1></div>
                

                <p class="para">
                    O elemento <em class="emphasis">&lt;classname&gt;</em> deve ser usado cada vez que um
                    nome de classe é representado sozinho. Não deve ser usado quando combinado com
                    um nome de método, nome de variável ou constante, e nenhum outro conteúdo é
                    permitido dentro do elemento.
                </p>

                <pre class="programlisting brush: xml">
&lt;para&gt;
    A classe &lt;classname&gt;Zend_Class&lt;/classname&gt;.
&lt;/para&gt;
</pre>

            </div>

            <div class="section" id="doc-standard.file-formatting.inline-tags.varname"><div class="info"><h1 class="title">varname</h1></div>
                

                <p class="para">
                    Variáveis devem ser envolvidas pelo elemento
                    <em class="emphasis">&lt;varname&gt;</em>. As variáveis devem ser escritas usando o
                    símbolo &quot;$&quot;. Nenhum outro conteúdo é permitido dentro deste elemento, exceto se
                    um nome de classe é usado, o que indica uma variável de classe.
                </p>

                <pre class="programlisting brush: xml">
&lt;para&gt;
    A variável &lt;varname&gt;$var&lt;/varname&gt; e a variável de classe
    &lt;varname&gt;Zend_Class::$var&lt;/varname&gt;.
&lt;/para&gt;
</pre>

            </div>

            <div class="section" id="doc-standard.file-formatting.inline-tags.methodname"><div class="info"><h1 class="title">methodname</h1></div>
                

                <p class="para">
                    Métodos devem ser envolvidos pelo elemento
                    <em class="emphasis">&lt;methodname&gt;</em>. Os métodos devem ou incluir sua
                    assinatura completa ou pelo menos um par de parênteses (por exemplo, &quot;()&quot;).
                    Nenhum outro conteúdo é permitido dentro do elemento, exceto se um nome de
                    classe é usado, o que indica um método de classe.
                </p>

                <pre class="programlisting brush: xml">
&lt;para&gt;
    O método &lt;methodname&gt;foo()&lt;/methodname&gt; e o método de classe
    &lt;methodname&gt;Zend_Class::foo()&lt;/methodname&gt;. Um método com uma assinatura
    completa: &lt;methodname&gt;foo($bar, $baz)&lt;/methodname&gt;
&lt;/para&gt;
</pre>

            </div>

            <div class="section" id="doc-standard.file-formatting.inline-tags.constant"><div class="info"><h1 class="title">constant</h1></div>
                

                <p class="para">
                    Use o elemento <em class="emphasis">&lt;constant&gt;</em> quando designar constantes.
                    As constantes devem ser escritas em <acronym class="acronym">MAIÚSCULAS</acronym>. Nenhum outro
                    conteúdo é permitido dentro deste elemento, exceto se um nome de classe é usado,
                    o que indica uma constante de classe.
                </p>

                <pre class="programlisting brush: xml">
&lt;para&gt;
    A constante &lt;constant&gt;FOO&lt;/constant&gt; e a constante de classe
    &lt;constant&gt;Zend_Class::FOO&lt;/constant&gt;.
&lt;/para&gt;
</pre>

            </div>

            <div class="section" id="doc-standard.file-formatting.inline-tags.filename"><div class="info"><h1 class="title">filename</h1></div>
                

                <p class="para">
                    Nomes de arquivos e caminhos devem ser envolvidos pelo elemento
                    <em class="emphasis">&lt;filename&gt;</em>. Nenhum outro conteúdo é permitido neste
                    elemento.
                </p>

                <pre class="programlisting brush: xml">
&lt;para&gt;
    O nome de arquivo &lt;filename&gt;application/Bootstrap.php&lt;/filename&gt;.
&lt;/para&gt;
</pre>

            </div>

            <div class="section" id="doc-standard.file-formatting.inline-tags.command"><div class="info"><h1 class="title">command</h1></div>
                

                <p class="para">
                    Comandos, shell scripts e chamadas de programa devem ser envolvidos pelo
                    elemento <em class="emphasis">&lt;command&gt;</em>. Se o comando incluir argumentos,
                    estes também devem ser incluídos dentro do elemento.
                </p>

                <pre class="programlisting brush: xml">
&lt;para&gt;
    Execute &lt;command&gt;zf.sh create project&lt;/command&gt;.
&lt;/para&gt;
</pre>

            </div>

            <div class="section" id="doc-standard.file-formatting.inline-tags.code"><div class="info"><h1 class="title">code</h1></div>
                

                <p class="para">
                    O uso do elemento <em class="emphasis">&lt;code&gt;</em> é desencorajado, em favor
                    dos outros elementos inline discutidos anteriormente.
                </p>
            </div>
        </div>

        <div class="section" id="doc-standard.file-formatting.block-tags"><div class="info"><h1 class="title">Notas sobre elementos de bloco específicos</h1></div>
            

            <div class="section" id="doc-standard.file-formatting.block-tags.title"><div class="info"><h1 class="title">title</h1></div>
                

                <p class="para">
                    O elemento <em class="emphasis">&lt;title&gt;</em> não permite ter elementos filhos.
                </p>

                <pre class="programlisting brush: xml">
&lt;!-- NÃO PERMITIDO --&gt;
&lt;title&gt;Usando &lt;classname&gt;Zend_Class&lt;/classname&gt;&lt;/title&gt;

&lt;!-- PERMITIDO --&gt;
&lt;title&gt;Usando Zend_Class&lt;/title&gt;
</pre>

            </div>
        </div>
    </div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="doc-standard.overview.html">Vis&atilde;o Geral</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="doc-standard.html">Norma sobre a documenta&ccedil;&atilde;o do Zend Framework</a></span><br />
                        <span class="home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="doc-standard.recommendations.html">Recomenda&ccedil;&otilde;es</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></li>
  <li class="header up"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></li>
  <li class="header up"><a href="doc-standard.html">Norma sobre a documenta&ccedil;&atilde;o do Zend Framework</a></li>
  <li><a href="doc-standard.overview.html">Vis&atilde;o Geral</a></li>
  <li class="active"><a href="doc-standard.file-formatting.html">Formata&ccedil;&atilde;o dos Arquivos de Documenta&ccedil;&atilde;o</a></li>
  <li><a href="doc-standard.recommendations.html">Recomenda&ccedil;&otilde;es</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>